﻿<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../helpproject.xsl" ?>
<topic template="Default" lasteditedby="Geert" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../helpproject.xsd">
  <title translate="true">Using the repositories and unit of work</title>
  <keywords>
    <keyword translate="true">EF</keyword>
    <keyword translate="true">Entity Framework</keyword>
    <keyword translate="true">EntityFramework</keyword>
    <keyword translate="true">Repositories</keyword>
    <keyword translate="true">Repository</keyword>
    <keyword translate="true">Unit of Work</keyword>
    <keyword translate="true">UoW</keyword>
  </keywords>
  <body>
    <header>
      <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Using the repositories and unit of work</text></para>
    </header>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The Repository and </text><link displaytype="text" defaultstyle="true" type="weblink" href="http://en.wikipedia.org/wiki/Unit_of_work" target="_blank" styleclass="Normal" translate="true">Unit of Work</link><text styleclass="Normal" translate="true"> (UoW) pattern are very useful patterns to create an abstraction level over the </text><text styleclass="Normal" style="font-style:italic;" translate="true">DbContext</text><text styleclass="Normal" translate="true"> that is provided by Entity Framework. A much heard excuse not to use repositories is that EF itself already works with repositories (the </text><text styleclass="Normal" style="font-style:italic;" translate="true">DbContext</text><text styleclass="Normal" translate="true">) and a UoW (in the </text><text styleclass="Normal" style="font-style:italic;" translate="true">SaveChanges </text><text styleclass="Normal" style="font-style:normal;" translate="true">method</text><text styleclass="Normal" translate="true">). Below are a few examples why it is a good thing to create repositories:</text></para>
    <list id="48" type="ul" listtype="bullet" formatstring="&#183;" format-charset="SYMBOL_CHARSET" levelreset="true" legalstyle="false" startfrom="1" styleclass="Normal (list)" style="font-family:Symbol; font-size:10pt; color:#000000;">
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Abstract away some of the more complex features of Entity Framework that the end-developer should not be bothered with</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Hide the actual DbContext (make it internal) to prevent misuse</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Keep security checks and saving and rollback in a single location</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Force the use of the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="Data_Specifications" styleclass="Normal (list)" translate="true">Specification pattern</link><text styleclass="Normal (list)" translate="true"> on queries</text></li>
    </list>
    <para styleclass="Notes"><text styleclass="Notes" translate="true">Note that repositories and UoW should not be used to abstract away the ORM tool because that is just another abstraction layer which is not required. Use it for the advantages mentioned above</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">A Unit of Work (UoW) is a a combination of several actions that will be grouped into a transaction. This means that either all actions inside a UoW are committed or rolled back. The advantage of using a UoW is that multiple save actions to multiple repositories can be grouped as a unit.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">A repository is a class or service responsible for providing objects and allowing end-developers to query data. Instead of querying the </text><text styleclass="Normal" style="font-style:italic;" translate="true">DbContext</text><text styleclass="Normal" translate="true"> directly, the </text><text styleclass="Normal" style="font-style:italic;" translate="true">DbContext</text><text styleclass="Normal" translate="true"> can be abstracted away to provide default queries and force required functionality to all end-developers of the </text><text styleclass="Normal" style="font-style:italic;" translate="true">DbContext</text><text styleclass="Normal" translate="true">.</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Overview of Unit of Work and repositories</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">There are different interpretations of how repositories should be used in combination with unit of work. Let&apos;s start with an overview how the DbContext, Repositories and Unit of Work relate to each other. The image below represents an overview of the situation as Catel deals with the DbContext, Repositories and Unit of Work:</text></para>
    <para styleclass="Normal"><image src="UnitOfWork_Repositories.png" scale="82.93%" width="413" height="299" styleclass="Image Caption"></image></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The image above shows that the Unit of Work is the top-level component to be used. Each UoW contains its own </text><text styleclass="Normal" style="font-style:italic;" translate="true">DbContext</text><text styleclass="Normal" translate="true"> instance. The </text><text styleclass="Normal" style="font-style:italic;" translate="true">DbContext</text><text styleclass="Normal" translate="true"> can either be injected or will be created on the fly. Then the UoW also contains repositories which always get the </text><text styleclass="Normal" style="font-style:italic;" translate="true">DbContext</text><text styleclass="Normal" translate="true"> injected. This way, all repositories inside a UoW share the same </text><text styleclass="Normal" style="font-style:italic;" translate="true">DbContext</text><text styleclass="Normal" translate="true">.</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Creating a Unit of Work</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">A UoW can be created by simply instantiating it. The end-developer has the option to either inject the </text><text styleclass="Normal" style="font-style:italic;" translate="true">DbContext</text><text styleclass="Normal" translate="true"> or let the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="DbContextManager" styleclass="Normal" translate="true">DbContextManager</link><text styleclass="Normal" translate="true"> take care of it automatically.</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">using</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">(var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">uow</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">new</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">UnitOfWork&lt;MyDbContext&gt;())</text><br/><text styleclass="Code Example" translate="true">{</text><br/><text styleclass="Code Example" translate="true"> &#160; &#160;// get repositories and query away</text><br/><text styleclass="Code Example" translate="true">}</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Creating a repository</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">A repository can be created very easily by deriving from the </text><text styleclass="Normal" style="font-style:italic;" translate="true">EntityRepositoryBase</text><text styleclass="Normal" translate="true"> class. Below is an example of a customer repository:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">class</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">CustomerRepository</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">:</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">EntityRepositoryBase&lt;Customer,</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">int</text><text styleclass="Code Example" translate="true">&gt;, ICustomerRepository</text><br/><text styleclass="Code Example" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">CustomerRepository(DbContext</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">dbContext)</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160; &#160; &#160;</text><text styleclass="Code Example" translate="true">:</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">base</text><text styleclass="Code Example" translate="true">(dbContext)</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" translate="true">{</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true"> &#160; &#160;</text><text styleclass="Code Example" translate="true">}</text><br/><text styleclass="Code Example" translate="true">}</text><br/><br/><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">public</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">interface</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">ICustomerRepository</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">:</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">IEntityRepository&lt;Customer,</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">int</text><text styleclass="Code Example" translate="true">&gt;</text><br/><text styleclass="Code Example" translate="true">{</text><br/><text styleclass="Code Example" translate="true">}</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Retrieving repositories from a Unit of Work</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Once a UoW is created, it can be used to resolve repositories. To retrieve a repository from the UoW, the following conditions must be met:</text></para>
    <list id="47" type="ol" listtype="decimal" formatstring="&#37;&#48;&#58;&#115;&#46;" format-charset="DEFAULT_CHARSET" levelreset="true" legalstyle="false" startfrom="1" styleclass="Normal (list)" style="font-family:Arial; font-size:10pt; color:#000000;">
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">The container must be registered in the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="Services" styleclass="Normal (list)" translate="true">ServiceLocator<title translate="true">IoC_ServiceLocator</title></link><text styleclass="Normal (list)" translate="true"> as </text><text styleclass="Normal (list)" style="font-style:italic;" translate="true">Transient</text><text styleclass="Normal (list)" translate="true"> type. If the repository is declared as non-transient, it will be instantiated as new instance anyway.</text></li>
      <li styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">The repository must have a constructor accepting a </text><text styleclass="Normal (list)" style="font-style:italic;" translate="true">DbContext</text><text styleclass="Normal (list)" style="font-style:normal;" translate="true"> instance</text></li>
    </list>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">To retrieve a new repository from the UoW, use the following code:</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">using</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">(var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">uow</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">new</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">UnitOfWork&lt;MyDbContext&gt;())</text><br/><text styleclass="Code Example" translate="true">{</text><br/><text styleclass="Code Example" translate="true"> &#160; &#160;var customerRepository = uow.GetRepository&lt;ICustomerRepository&gt;();</text><br/><br/><text styleclass="Code Example" translate="true"> &#160; &#160;// all interaction with the customer repository is applied to the unit of work</text><br/><text styleclass="Code Example" translate="true">}</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Saving a Unit of Work</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">It is very important to save a Unit of Work. Once the Unit of Work gets out of scope (outside the using), all changes will be discarded if not explicitly saved.</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">using</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">(var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">uow</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:bold; font-style:normal; color:#000000;" translate="true">new</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" translate="true">UnitOfWork&lt;MyDbContext&gt;())</text><br/><text styleclass="Code Example" translate="true">{</text><br/><text styleclass="Code Example" translate="true"> &#160; &#160;var customerRepository = uow.GetRepository&lt;ICustomerRepository&gt;();</text><br/><br/><text styleclass="Code Example" translate="true"> &#160; &#160;// all interaction with the customer repository is applied to the unit of work</text><br/><br/><text styleclass="Code Example" translate="true"> &#160; &#160;uow.SaveChanges();</text><br/><text styleclass="Code Example" translate="true">}</text></para>
    <para styleclass="Normal"></para>
  </body>
</topic>
